Documentation on sfind
Task: sfind
Purpose: Interactively find sources in images on a PGPLOT device
Categories: plotting
SFIND displays an image via a contour plot or a pixel map
representation on a PGPLOT device. The user is then provided
with the opportunity to interactively flag sources as real or
not (indicated by a Y or N flag in a log file).
Source positions are calculated by an algorithm which searches for
pixels brighter than the surrounding 24 pixels and then
bi-parabolically fitting positions and flux densities.
Once a source such as this is detected, SFIND checks to see whether
it is brighter than the user set multiple of the background rms.
If so, a 2D elliptical gaussian fit is performed (using the same
routine as IMFIT) and the source parameters are displayed on the
terminal (and written to a log file after user input to determine
a flag, Y or N, to attach). The source parameters are (in order):
Quantity Notes
-------------- -----------
Position RA and Dec. in standard miriad
hms,dms format
Formal errors in RA and Dec. (arcsec; treat judicously)
Peak flux density (mJy)
Formal error in peak flux in mJy (generally not a good
density estimate of the true error)
Integrated flux density (mJy)
Major and minor axes and (arcseconds for axes, degrees for PA)
position angle of source Warning: these are not deconvolved
from the synthesized beam
Local background rms (sigma) (mJy) can be misleading if source is
close to other comparitively bright
sources (ie, they will be included in
region surrounding source within which
the background rms is calculated)
rms of gaussian fit
Manipulation of the device colour lookup table is available
when you display with a pixel map representation.
Key: in
The input image.
Key: type
Specifies the type of the image in the IN keyword. Minimum match
is supported. Choose from:
"contour" (contour plot)
"pixel" (pixel map)
It is strongly suggested that pixel maps be used for source finding,
as contour plots may be deceiving. Default is "pixel"
Key: region
Region of interest. Choose only one spatial region (bounding
box only supported), but as many spectral regions (i.e.,
multiple IMAGE specifications) as you like. If you display a
3-D image, the cursor options are activated after each sub-plot
(channel or group of channels; see CHAN below) is drawn.
Default is full image
Key: xybin
Upto 4 values. These give the spatial increment and binning
size in pixels for the x and y axes to be applied to the selected
region. If the binning size is not unity, it must be equal
to the increment. For example, to bin up the image by 4 pixels in
the x direction and to pick out every third pixel in the y
direction, set XYBIN=4,4,3,1
Defaults are 1,XYBIN(1),XYBIN(1),XYBIN(3)
Key: chan
2 values. The first is the channel increment, the second is
the number of channels to average, for each sub-plot. Thus
CHAN=5,3 would average groups of 3 channels together, starting
5 channels apart such as: 1:3, 6:8, 11:13 ... The channels
available are those designated by the REGION keyword. A new
group of channels (sub-plot) is started if there is a
discontinuity in the REGION selected channels (such as
IMAGE(10,20),IMAGE(22,30).
Defaults are 1,1
Key: slev
2 values. First value is the type of contour level scale
factor. "p" for percentage and "a" for absolute. Second
value is the level to scale LEVS by. Thus SLEV=p,1 would
contour levels at LEVS * 1% of the image peak intensity.
Similarly, SLEV=a,1.4e-2 would contour levels at LEVS * 1.4E-2
Default is no additional scaling of LEVS
Key: levs
Levels to contour for first image, are LEVS times SLEV
(either percentage of the image peak or absolute).
Defaults try to choose something sensible
Key: range
3 values. The pixel map range (background to foreground), and
transfer function type. The transfer function type can be one
of "lin" (linear), "log" (logarithmic), "heq" (histogram equal-
ization), and "sqr" (square root). See also OPTIONS=FIDDLE which
is in addition to the selections here.
Default is linear between the image minimum and maximum
If you wish to just give a transfer function type, set
range=0,0,heq say.
Key: cutoff
Flux density below which possible sources are ignored. No default.
Key: rmsbox
Size (in pixels) of a box around each source within which the
background rms is calculated. Default is 20 pixels.
Key: xrms
Multiple of the background rms value above which a source must be
before the user is given the choice of verifying it. No default.
Key: device
The PGPLOT plot device, such as plot.plt/ps. No default.
Key: nxy
Number of sub-plots in the x and y directions on the page.
Defaults choose something sensible
Key: labtyp
Two values. The spatial label type of the x and y axes.
Minimum match is active. Select from:
"hms" the label is in H M S (e.g. for RA)
"dms" the label is in D M S (e.g. for DEC)
"arcsec" the label is in arcsecond offsets
"arcmin" the label is in arcminute offsets
"absdeg" the label is in degrees
"reldeg" the label is in degree offsets
The above assume the pixel increment is in radians.
"abspix" the label is in pixels
"relpix" the label is in pixel offsets
"abskms" the label is in Km/s
"relkms" the label is in Km/s offsets
"absghz" the label is in GHz
"relghz" the label is in GHz offsets
"absnat" the label is in linear coordinates as defined by
the header you might call this the natural axis label
"relnat" the label is in offset natural coordinates
All offsets are from the reference pixel.
Defaults are "abspix", LABTYP(1) unless LABTYP(1)="hms"
whereupon LABTYP(2) defaults to "dms" (for RA and DEC).
Key: options
Task enrichment options. Minimum match is active.
"fiddle" means enter a routine to allow you to interactively change
the display lookup table. You can cycle through b w and colour
displays, as well as alter the transfer function by the cursor
location, or by selecting predefined transfer functions such as
histogram equalization, logarithmic, square root.
"wedge" means that if you are drawing a pixel map, also draw
and label a wedge to the right of the plot, showing the map
of intensity to colour
"3value" means label each sub-plot with the appropriate value
of the third axis (e.g. velocity or frequency for an xyv ordered
cube, position for a vxy ordered cube).
"3pixel" means label each sub-plot with the pixel value of the
the third axis. Both "3pixel" and "3value" can appear, and both
will be written on the plot. They are the average values when
the third axis is binned up with CHAN. If the third axis is
not velocity or frequency, the units type for "3VALUE" will be
chosen to be the complement of any like axis in the first 2.
E.g., the cube is in vxy order and LABTYP=ABSKMS,ARCSEC the units
for the "3VALUE" label will be arcsec. If LABTYP=ABSKMS,HMS the
"3VALUE" label will be DMS (if the third [y] axis is declination).
"grid" means draw a coordinate grid on the plot rather than just ticks
"noerase" Don't erase a snugly fitting rectangle into which the
"3-axis" value string is written.
"unequal" means draw plots with unequal scales in x and y. The
default is that the scales are equal.
"mark" When source has been found, and user has agreed that it is
real, mark it with a cross.
"nofit" Prevents the program from fitting elliptical gaussians to each
source. The data given on each source will be that from a
bi-parabolic fit, as per the earlier version of sfind. Note that
flux densities from this fit are bi-parabolically fitted *peak*
flux densities, and the positions are to the peak flux density
position (which will always be within 1 pixel of the brightest
pixel in the source). This option is useful for providing a starting
point for groups of sources which the gaussian fitting procedure
hasn't taken a liking to.
"asciiart" During the interactive section of the program, an ascii
picture of each source is displayed, showing which pixels have
been used in the gaussian fitting procedure. The brightest pixel
in the source is symbolised by a "O", the rest by asterisks.
This option is ignored if "nofit" is being used.
Key: csize
Two values. Character sizes in units of the PGPLOT default
(which is ~ 1/40 of the view surface height) for the plot axis
labels and the velocity/channel labels.
Defaults choose something sensible.
Known Bugs:
The output is designed to print source fluxes in FORTRAN format
f8.3 and f9.3 for peak and integrated flux densities respectively.
This means that if your source's peak flux is 9999.999 mJy, (ie
10 Jy) or its integrated flux is 99999.999 mJy (ie, 100 Jy),
then it will not be displayed properly. People detecting very bright
sources - you have been warned!
The gaussian fitting procedure can at times be temperamental. If the
source lies in a noisy region of the map, or close to another bright
source, or is simply of a morphology poorly suited to being fit by
gaussians, firstly the source may not be detected at all, and if it
is, the quoted errors on position and flux density can be extremely
high (often displayed in the output as a row of asterisks due to the
vagaries of FORTRAN).
In many of these cases, the given values of flux density and position
are still quite reasonable, (perhaps with errors an order of magnitude
larger than would otherwise be typical), but user discretion is
advised. No responsibility is taken by the programmer(s) for loss
of life or property caused by taking the results of this program
under these conditions too seriously, or by frustration generated
by the use of this program under any conditions.
Additionally, for unresolved sources, the "integrated" flux
density quoted may be less than the peak flux density. (This occurs if
the fitted size of the source, proportional to bmaj x bmin, is a
smaller gaussian volume than that of the beam.) In this situation it
is suggested that the peak flux density be used.
Suggestions for believing in a source or not:
If a source is close to being indistinguishable by eye from the
background there are a few rules of thumb to help determine whether
the gaussian fit is telling the truth about a source, or whether the
source is even real.
1) If the pixels used in the fit are widely scattered (as opposed to
comprising a nice contiguous group) the fit will probably not be
very good and/or will not be a good description of the source.
2) Check the fwhms and the position angle, and compare it to the
pixels used in the fit. (Remember these values are in arcsec for
the fwhm and degrees for the pa, while the ascii picture is in
pixels). If these obviously do not agree, then the fit was poor
and the source is probably not real.
3) Check the rms of the background. If this is high then firstly
the fit may not be good (as per 1), and secondly the source is in
a noisy area and should be treated with caution anyway.
Generated by rsault@atnf.csiro.au on 11 Jul 1996